﻿<h1>The Official Go SDK</h1>

<p>
Currently, the tools in the official Go SDK are the most used tools to develop Go projects.
In Go 101 article series, all examples are compiled and verified with the standard Go compiler.
</p>

<p>
This article will introduce how to setup the Go development environment
and how to run simple Go programs.
Some tools of the official Go SDK will also be introduced.
</p>

<h3>Install Go SDK</h3>

<p>
Please <a href="https://golang.org/doc/install">download</a> the official Go SDK
and install it according to the instructions shown in the download page.
</p>

<p>
The version of an official Go SDK release is consistent with
the highest Go language version the release supports.
For example, the latest Go SDK 1.13.x supports all Go language versions from 1.0 to Go 1.13.
</p>

<p>
The path to the <code>bin</code> subfolder in the Go SDK installation root path
must be put in the <code>PATH</code> environment variable to execute the tools
(mainly the <code>go</code> subcommands) in the SDK without inputting their full paths.
If your Go SDK is installed with an installer or with a package manager, the path to
the <code>bin</code> subfolder may have been already set in the <code>PATH</code>
environment variable automatically for you.
</p>

<p>
Earlier Go SDK versions might require <code>GOROOT</code> and
<code>GOPATH</code> environment variables to be set.
The latest Go SDK has no such requirements.
The default value of the <code>GOPATH</code> environment variable is
the path to the <code>go</code> folder under the home directory of the current user.
<code>GOPATH</code> environment variable may list multiple paths.
</p>

<p>
There is a <code>GOBIN</code> environment variable which controls
where the binary files generated by some <code>go</code> subcommands,
such as the <code>go install</code> subcommand (see below), will be stored.
If the environment variable is not set, the <code>go</code> command will
use the path to <code>bin</code> subfolder in the first path specified in the
<code>GOPATH</code> environment variable to store the generated binary files.
The path to the folder for storing the binary files should be set in the <code>PATH</code>
environment variable to run the binary files without specifying their full paths.
</p>

<p>
Before Go SDK 1.11, it is recommended to put all custom Go packages into the
<code>src</code> subfolder of any path specified in the <code>GOPATH</code> environment variable,
in particular when a Go project depends on some third party packages.
Packages will be introduced in <a href="packages-and-imports.html">packages and imports</a> later.
</p>

<p>
In Go SDK 1.11, an experimental feature, Go modules, is supported.
The Go modules feature lets us put our Go projects freely in any folder.
We can get more module releated information from
<a href="https://github.com/golang/go/wiki/Modules">this wiki page</a>.
</p>

<p>
Note, since Go SDK 1.13,
the Go modules feature will become as the preferred mode (to the old <code>GOPATH</code> mode).
The necessity and meaningfulenss of the <code>GOPATH</code> environment variable
will be weakened much, even be abolished eventually.
On the other hand, the importance of the <code>GOBIN</code> environment variable will be promoted,
for there is still a need to store the binary files produced by some <code>go</code> subcommands.
</p>

<!--
<p><i>
(Before Go SDK 1.9, a <code>GOROOT</code> environment variable had to be configured
as the root path of the SDK installation.
<a href="https://golang.org/doc/go1.9#goroot">With Go SDK 1.9</a>,
this environment variable became optional, and it is recommended to leave it unset.)
</i></p>

<p>
Before Go SDK 1.8, a <code>GOPATH</code> environment variable must be set.
<a href="https://golang.org/doc/go1.8#gopath">Since Go SDK 1.8</a>,
the default value of this environment variable is the path of the <code>go</code>
folder under the home directory of the current user.
You may specify <code>GOPATH</code> manually in order to work with one (or more) different location(s).
Yes, the <code>GOPATH</code> environment variable may list multiple paths.
</p>
-->

<h3>The Simplest Go Program</h3>

<div>
<p>
Let's write a simple example and learn how to run simple Go programs.
</p>

The following program is the simplest Go program.
<pre class="line-numbers must-line-numbers fixed-width"><code class="language-go">package main

func main() {
}
</code></pre>

<p>
The words <code>package</code> and <code>func</code> are two keywords.
The two <code>main</code> words are two identifiers.
Keywords and identifiers are introduced in
<a href="keywords-and-identifiers.html">a coming article</a>.
</p>

<p>
The first line <code>package main</code> specifies the package name
(<code>main</code> here) of the source file.
</p>

<p>
The second line is a blank line for better readability.
</p>

<p>
The remaining code declares a function
which is also called <code>main</code>.
This <code>main</code> function in a <code>main</code> package
specifies the entry point of a program.
(Note that some other user code might be executed
before the <code>main</code> function gets invoked.)
</p>

</div>

<h3>Run Go Programs</h3>

<div>

<p>
The official Go SDK requires that Go source code file
to have the extension <code>.go</code>.
Here, we assume the above source code is saved in a file
named <code>simplest-go-program.go</code>.
</p>

Open a terminal and change the current directory to the directory
which contains the above source file, then run
<pre class="output"><code>$ go run simplest-go-program.go
</code></pre>

<p>
Nothing is output? Yes, this program outputs nothing.
</p>

<p>
If there are some syntax errors in the source code,
then these errors will be reported as compilation errors.
</p>

Note: if multiple source files are
in the <code>main</code> package of a program,
then we should run the program with the following command
<pre class="output"><code>$ go run .
</code></pre>

<p>
Note, the <code>go run</code> command is not recommended
to compile and run large Go projects.
It is just a convenient way to run simple Go programs,
like the ones in the Go 101 articles.
For large Go projects,
please use the commands <code>go build</code> or <code>go install</code>
to build and create executable binary files instead.
</p>

</div>

<h3>More <code>go</code> Subcommands</h3>


<p>
The three commands, <code>go run</code>, <code>go build</code> and <code>go install</code>,
only output code syntax errors (if any).
They don't (try to) output code warnings (a.k.a., possible code logic mistakes).
We can use the <code>go vet</code> command to check and report such warnings.
</p>

<p>
We can use the <code>go fmt</code> command to format Go source code
with a consistent coding style.
</p>

<p>
We can use the <code>go get</code> command to get a remote third-party go package to lcoal.
<code>go get</code> requires the corresponding version control tool must be installed.
</p>

<p>
We can use the <code>go test</code> command to run tests and benchmarks.
</p>

<p>
We can use the <code>go doc</code> command to view Go documentation in terminal windows.
</p>

<p>
Since Go SDK 1.11, we can use the <code>go mod</code> command to manage dependencies.
</p>

<p>
We can use the <code>go help aSubCommand</code> command to view the help message for a specified sub command.
</p>

<p>
The <code>go</code> command run without any arguments
shows the supported subcommands.
</p>

<p>
The Go 101 article series will not explain much more on how to use the tools
provided by the official Go SDK.
Please read the <a href="https://golang.org/cmd/go/">official documentation</a> for details.
</p>

<a class="anchor" id="doc"></a>
<h3>View Go Documentation in Browsers</h3>

<div>
<p>
We can view all kinds of Go documentation at the official Go
website <a href="https://golang.org">golang.org</a>.
</p>

<p>
We can also run <code>godoc -http=:9999</code> to start a local clone of the
official website at <a href="http://localhost:9999">localhost:9999</a>.
</p>

Please note,
<ul>
<li>
	since Go SDK 1.13, the <code>godoc</code> command <a href="https://golang.org/doc/go1.12">has been removed from Go SDK</a>.
	Please run <code>go get golang.org/x/tools/cmd/godoc</code> to install it separately.
</li>
<li>
	for Go SDK 1.10, if the <code>GOROOT</code> environment variable is unset,
	we must specify the <code>goroot</code> flag when running the local godoc server,
	e. g. <code>godoc -http=:9999 -goroot path/to/go/sdk</code>.
	This inconvenience is caused by a bug in Go SDK 1.10.
	This bug has been fixed since Go SDK 1.11.
</li>
<li>
	since Go SDK 1.12, the documentation "A Tour of Go" is not packaged in Go SDK any more.
	We can run <code>go get golang.org/x/tour; tour</code> to view the documentation locally.
</li>
</ul>

<p>
Currently (Go SDK 1.13), the <code>godoc</code> command doesn't support showing documentation
of packages outside of the paths specified in the <code>GOPATH</code> environment variable.
</p>

<p>
The <code>godoc</code> command tries to list the documentation of all the packages
under the paths specified in the <code>GOPATH</code> environment variable.
If you only want to view the documentation of the standard packages,
you can set the <code>GOPATH</code> environment variable to a non-exist path
before running <code>godoc</code>, for example, run <code>GOPATH=nonexist godoc -http=:9999</code> on Linux.
</p>

<!--
up to 1.9: https://github.com/golang/go/issues/15049
https://groups.google.com/forum/#!msg/golang-dev/tqsatm29V9E/wbRUwJ-ZtUIJ
-->

</div>

